[release-1.7.3]: https://github.com/HuolalaTech/page-spy-web/releases/tag/v1.7.3
[public-data-event]: https://github.com/HuolalaTech/page-spy/blob/main/docs/plugin_zh.md#행동-규약

import modalImg from '@/assets/image/screenshot/modal.png';
import replayImg from '@/assets/image/screenshot/replay-page.png';
import replayGif from '@/assets/image/screenshot/replay-page.gif';
import mpDataHarborImg from '@/assets/image/screenshot/mp-data-harbor.png';

**로그 재생**이란 말 그대로 이전에 생성된 로그를 다시 재생하는 것입니다. 그렇다면 왜 이전 로그를 재생해야 할까요? 이전 로그는 어디서 오는 걸까요? 어떻게 재생할 수 있을까요? 하나씩 살펴보겠습니다.

<a href={replayGif} target="_blank">
  <img src={replayGif} />
</a>

## 왜 필요한가#why

그동안 PageSpy의 온라인 디버깅은 많은 까다로운 문제를 해결했지만, PageSpy를 사용하기 위해서는 전제 조건이 있었습니다: "클라이언트와 디버그 측이 동시에 온라인 상태여야 한다". 이 전제 조건은 PageSpy의 사용 시나리오를 제한했습니다. 예를 들면:

- 하나의 문제를 해결하기 위해 개발자와 테스터 두 명의 인력이 동시에 투입되어야 함
- 디버깅 중에 클라이언트가 백그라운드로 전환되어 연결이 끊어짐

동시에 PageSpy 자체에도 제약을 가져왔습니다. 예를 들면:

- 수집하는 데이터의 용량, 네트워크 전송의 부하를 고려해야 함

이러한 문제들을 해결하고 더 큰 자유도를 얻기 위해, PageSpy는 [1.7.3][release-1.7.3] 버전에서 로그 재생 기능을 제공하게 되었습니다!

## 로그는 어디서 오는가#where

PageSpy의 SDK가 [플러그인 등록](./plugins)을 지원하게 된 후, 개발팀은 즉시 [DataHarborPlugin]({VITE_PLUGIN_DATA_HARBOR}) 플러그인의 개발을 추진했습니다.

> `Data Harbor`, 데이터 항구.
> 
> 멘탈 모델: PageSpy가 생성하는 데이터는 끊임없이 "데이터 항구"로 전송되며, 데이터의 정리, 패키징, 압축 후에 "데이터 항구"는 데이터를 "컨테이너"(메모리 또는 로컬 임시 파일)에 저장하고 다음 지시를 기다립니다.

내부적으로 `"public-data"` 이벤트([`"public-data"` 이벤트란?](./plugins#convention))를 모니터링하여 오프라인 데이터 캐시 기능을 구현하고, SDK가 렌더링하는 컨트롤에서 데이터 업로드 및 다운로드 기능을 제공합니다. 클라이언트에서 문제가 발견되면 테스터는 직접 데이터를 업로드하거나 다운로드할 수 있습니다. 이러한 혁신으로 기존의 "클라이언트와 디버그 측이 동시에 온라인 상태여야 한다"는 전제 조건이 해소되었습니다.

## 사용 방법#how-to-use

### 브라우저에서 사용#browser

> PageSpy의 오프라인 로그 재생 기능만 필요한 경우, 더 쉽게 통합할 수 있는 [O-Spy](#use-ospy)의 사용을 추천합니다.

#### 1단계: 클라이언트에 SDK와 플러그인 도입#step-1

```html
<html>
  <head>
    <!-- 1. PageSpy 로드 -->
    <script src="{deployUrl}/page-spy/index.min.js"></script>
    <!-- 2. DataHarbor 플러그인 로드: 오프라인 로그 데이터 캐시, 다운로드/업로드 기능 제공 -->
    <script src="{deployUrl}/plugin/data-harbor/index.min.js"></script>
    <!-- 3. RRWeb 플러그인도 로드하여 사용자 조작 궤적을 오프라인 로그에 기록 가능 -->
    <script src="{deployUrl}/plugin/rrweb/index.min.js"></script>

    <script>
      // 4. 플러그인 등록, config 정보는 다음 참조: https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-data-harbor
      PageSpy.registerPlugin(new DataHarborPlugin(config));
      PageSpy.registerPlugin(new RRWebPlugin());

      // 5. PageSpy 인스턴스화
      window.$pageSpy = new PageSpy({
        // SDK와 디버그 측이 실시간 연결을 설정하지 않으려면 오프라인 모드를 활성화할 수 있습니다
        // offline: true
      });
    </script>
  </head>
</html>
```

정상적으로 도입되면 페이지 우측 하단에 PageSpy의 플로팅 볼이 나타나며, 플로팅 볼을 클릭하면 표시되는 대화상자에 업로드와 다운로드 버튼이 포함되어 있어야 합니다.

<a href={modalImg} target="_blank">
  <img src={modalImg} />
</a>

#### 2단계: 로그 재생#step-2

디버그 측에 들어가서 상단 메뉴의 "디버그 시작 - 로그 재생"을 클릭하여 재생 목록 페이지로 이동한 후, 이전 단계에서 업로드/다운로드한 json 데이터를 선택하면 재생 기능을 사용할 수 있습니다!

<a href={replayImg} target="_blank">
  <img src={replayImg} />
</a>

#### 다른 플러그인과 함께 사용#plugins

DataHarborPlugin은 데이터 수집과 데이터 처리 기능만을 제공합니다. PageSpy는 추가로 다음과 같은 플러그인을 제공합니다:

- [RRWebPlugin]({VITE_PLUGIN_RRWEB}): `rrweb`를 사용하여 DOM 업데이트를 기록하고, 디버그 측의 "로그 재생" 패널 좌측에서 사용자의 조작 궤적을 확인할 수 있습니다.

### O-Spy 사용하기#use-ospy

[O-Spy](/o-spy)의 SDK는 플러그 앤 플레이 방식으로, 별도의 배포가 필요 없습니다. PageSpy / DataHarborPlugin / RRWebPlugin이 패키지로 포함되어 있으며, 오프라인 상태에서의 PageSpy 최적 설정이 내장되어 있습니다. 또한 사용자 정의 테마도 지원하여 매우 간단하게 사용할 수 있습니다.

프레임워크와 무관하게 프로젝트에 도입하는 방법을 자유롭게 선택할 수 있습니다.

import { ImportGuide } from '@/pages/OSpy/components/ImportGuide';

<ImportGuide />

정상적으로 도입되면 우측 하단에 "문제 피드백" 드래그 가능한 컴포넌트가 나타납니다.

#### 사용자 정의 테마 예시#customize-example

import { CustomizeExample } from '@/pages/OSpy/components/Customize';

<CustomizeExample />

### 미니프로그램에서 사용#mp

미니프로그램 환경에서도 오프라인 로그 재생을 지원합니다. 단계는 다음과 같습니다:

#### 1단계: 미니프로그램 전용 플러그인 설치#mp-step-1
```bash
yarn add @huolala-tech/page-spy-plugin-mp-data-harbor
```

#### 2단계: 플러그인 등록#mp-step-2
```ts
import PageSpy from '@huolala-tech/page-spy-wechat';
import DataHarborPlugin from '@huolala-tech/page-spy-plugin-mp-data-harbor';

// 플러그인 등록, config 정보는 다음 참조: https://github.com/HuolalaTech/page-spy/blob/main/packages/page-spy-plugin-mp-data-harbor
const $dataHarborPlugin = new DataHarborPlugin(config)
PageSpy.registerPlugin($dataHarborPlugin);

const $pageSpy = new PageSpy({
  // ...
})
```

#### 3단계: 오프라인 로그 업로드#mp-step-3

오프라인 로그를 업로드하는 방법에는 두 가지가 있습니다:

1. 플러그인 인스턴스의 `upload()` 메서드 호출:
```ts
$dataHarborPlugin.upload().then(() => {
  console.log('업로드 성공');
})
```

2. 미니프로그램 DataHarbor 플러그인을 등록하면 PageSpy의 디버그 메뉴에 "오프라인 로그 업로드" 버튼이 나타납니다. 이 버튼을 클릭하면 오프라인 로그를 업로드할 수 있습니다:

<a href={mpDataHarborImg} target="_blank">
  <img style={{width: 375}} src={mpDataHarborImg} />
</a>

### 차이점#diff

1. 미니프로그램 환경에서는 화면 녹화를 지원하지 않으며, 관련된 `RRWebPlugin`도 없습니다.

2. 미니프로그램 환경의 오프라인 로그는 업로드만 지원하고 다운로드는 지원하지 않습니다.

## FAQ#faq

1. 로그를 수동으로 업로드/다운로드하는 방법은 무엇인가요?

[여기를 참조하세요](./data-harbor#onOfflineLog).

2. 오프라인 로그는 어디에 저장되나요?

`DataHarborPlugin`이 데이터를 수신하면 먼저 메모리의 배열에 저장됩니다. 배열에 저장된 데이터의 크기가 임계값에 도달하면 데이터는 임시 파일에 기록됩니다. 이 임계값은 기본적으로 10MB입니다. 다음과 같이 직접 설정할 수도 있습니다:

```ts
new DataHarborPlugin({
  maximum: 1 * 1024 * 1024, // 메모리의 데이터 기록이 1MB에 도달하면 임시 파일에 기록
})
```
